home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / amiga / modelers / t3d / igensurf.doc < prev    next >
Text File  |  1991-09-29  |  15KB  |  458 lines
  1.                     igensurf v. 1.0.
  2.                   ====================
  3.  
  4. 1. Introduction:
  5. -----------------
  6.  
  7. igensurf is a program to generate a TTDDD description of a  functional
  8. surface.   The  TTDDD  description  can  then  be converted to Imagine
  9. object files with the WriteTDDD utility written by Glenn Lewis.
  10.  
  11. The functional surface is defined by  three  user  supplied  functions
  12. x(s,t),  y(s,t)  and z(s,t) where s and t will be varying from 0 to 1.
  13. The surface normal is defined by the right hand  rule  as  applied  to
  14. (s,t).
  15.  
  16. It is possible to create a very wide class of objects  with  igensurf.
  17. In  fact, I can't offhand think of an object which couldn't be created
  18. with it (although it often would be much easier to create  the  object
  19. with the Imagine editors).
  20.  
  21. The language  used  to  define  the  surface  contains  arithmetic  if
  22. statements  and  'switch'  statements  as  well  as a lot of different
  23. mathematical functions. Just to make things more interesting, you also
  24. have access to different noise functions, so that it  is  possible  to
  25. create landscapes etc.
  26.  
  27. Furthermore igensurf can be used to create  objects  based  on  bezier
  28. patches,  you  can  find  an  example  of  this in 'teapot.cal' in the
  29. examples directory.
  30.  
  31. You'll need some knowledge of mathematics to use this program.
  32.  
  33.  
  34.  
  35. 2. Command options:
  36. --------------------
  37.  
  38. The igensurf command has a rather complex syntax, but  it  gives  very
  39. good control over the objects you might want to create:
  40.  
  41.         igensurf [-n name] [-s step_s] [-t step_t]
  42.                  [-C] [-R] [-T] [-S scale_factor] [-p] [-v]
  43.                  [-e expression] [-o output_file] input_file ...
  44.  
  45. Don't panic, you don't have to use all the options at the same time :-)
  46.  
  47. Lets have a look at the arguments:
  48.  
  49.   -n name:
  50.     This defines the name of the created object.
  51.     If the name isn't supplied, the name "IGENSURF" is used.
  52.     It is possible to change  the  name  with  the  #name,  #write  or
  53.     #generate commands (see later).
  54.  
  55.   -S scale_factor
  56.     This option defines a scale factor  which  is  multiplied  on  the
  57.     functions before the object is generated.
  58.  
  59.     For instance would
  60.  
  61.     -e "x(s,t)=s; y(s,t)=t; z(s,t)=0" -S 100
  62.  
  63.     define a flat square with a side length of 100.
  64.  
  65.     It is possible to change the scale factor with the #scale command.
  66.  
  67.   -s step_s
  68.   -t step_t
  69.     Any imagine object (except perfect spheres)  consist  of  lots  of
  70.     triangles.  The  -s  and  -t options define how many triangles the
  71.     object should consist of, and thereby the size of these triangles:
  72.     
  73.     igensurf varies s from 0 to 1 in steps of 1/step_s, and  varies  t
  74.     from  0  to 1 in steps of 1/step_t. For each step it will create 2
  75.     triangles.  Because of this igensurf will  create  2  *  step_s  *
  76.     step_t triangles.
  77.  
  78.     The created object will look very faceted if step_s and step_t  is
  79.     small, and will be more smooth if these values are bigger.
  80.     The defaults for these values are 10.
  81.  
  82.     step_s and step_t is available in expressions and functions. It is
  83.     possible  to  override the values by changing the variables step_s
  84.     and step_t in an expression.
  85.  
  86.     It is necessary to be careful when selecting values for step_s and
  87.     step_t, otherwise you could end up with an acute case of aliassing
  88.     or digital bouncing as Impulse calls it:
  89.     
  90.     Lets assume that the functional expression contain the following:
  91.     
  92.         sin(10 * PI * s)
  93.     
  94.     In this case, it would be a disaster to use '-s 10'! The reason is
  95.     that the the expression then would be evaluated for s = 0.0,  0.1,
  96.     0.2, ... 1.0.
  97.     As you probably can see, the above expression is 0 for  all  these
  98.     values,  which  probably wasn't what you wanted. In this case, you
  99.     should either change -s  10  to  something  else,  or  modify  the
  100.     equation.
  101.  
  102.   -C
  103.     It is possible to assign different colors  to  the  faces  of  the
  104.     object; you can do this by defining three functions cr(s,t,x,y,z),
  105.     cg(s,t,x,y,z) and cb(s,t,x,y,z). 
  106.    
  107.     cr defines the amount of red (0.0 to 1.0), cg defines  the  amount
  108.     of green, and cb defines the amount of blue.
  109.  
  110.     The functions are called with the following arguments:
  111.         s, t   : The current values of s and t.
  112.     x, y, z: The coordinates of the centre of the face.
  113.          BEFORE the scale factor has been applied!
  114.                  
  115.     You  tell  igensurf   to  use  these functions by supplying the -C
  116.     option.  You  could  use  the  command  "#color  on"  to  activate
  117.     computation of colors instead of using the option.
  118.  
  119.     Here is a simple example:
  120.  
  121.     Lets presume that you have created  a  file,  test.cal,  with  the
  122.     following lines:
  123.     
  124.         x(s,t) = 100 * s;
  125.         y(s,t) = 0;
  126.         z(s,t) = 100 * t;
  127.         cr(s,t,x,y,z) = z;
  128.         cg(s,t,x,y,z) = z;
  129.         cb(s,t,x,y,z) = z;
  130.     
  131.     In this case, the command
  132.     
  133.         igensurf -s 10 -t 10 -C test.cal
  134.         
  135.     would result in a flat square which would be black at  the  bottom
  136.     and white at the top.
  137.  
  138.  
  139.   -R
  140.     You can assign different reflectance values (r, g and  b)  to  the
  141.     faces  of  the  object  by  using the -R options and supplying the
  142.     functions rr(s,t,x,y,z), rg(s,t,x,y,z) and rb(s,t,x,y,z).
  143.     The command "#refl on" could be used instead of the -R option.
  144.  
  145.   -T
  146.     You can assign different transmittance values (r, g and b) to  the
  147.     faces  of  the  object  by  using the -T options and supplying the
  148.     functions tr(s,t,x,y,z),  tg(s,t,x,y,z)  and  tb(s,t,x,y,z).   
  149.     The command "#trans on" could be used instead of the -T option.
  150.  
  151.  
  152.   -p 
  153.     As mentioned above, you can smooth the object by increasing step_s
  154.     and/or step_t.  This  will,  however,  create  objects  with  more
  155.     triangles  which  is  costly both in memory and in rendering time.
  156.     Another way to create smooth objects is by giving the  -p  option.
  157.     This  will tell Imagine to use Phong shading on the object.  Phong
  158.     shading normally works very  well,  but  it  doesn't  enhance  the
  159.     objects  silhouette  at all.  Phong shading is cheap in memory and
  160.     rendering time. 
  161.     You can also activate phong smoothing with the "#phong on" command.
  162.  
  163.   -v
  164.     igensurf can be rather slow.   If  you  use  the  -v  option,  the
  165.     program  will  tell you what it is doing, so that you can see that
  166.     it still is working.
  167.  
  168.   -e expr
  169.     Normally, you will write expressions and functions in a file, and
  170.     supply the filename as an argument to igensurf.
  171.     You may instead define these functions with the -e option.  It is
  172.     legal to specify the -e option more than once.
  173.  
  174.     Here is a very simple example:
  175.  
  176.     The options
  177.  
  178.       -e "x(s,t)=s;y(s,t)=t;z(s,t)=0"
  179.  
  180.     defines a flat square with a side length of 1.
  181.     
  182.  
  183.   -o output_file
  184.     If output_file is given on the command_line, the  output  will  be
  185.     written  to  this  file,  otherwise  the output will be written to
  186.     stdout.
  187.  
  188.   input_file ...
  189.     If you are using some complex expressions, it  probably  would  be
  190.     easier to create a file containing  these  expressions.  Then  you
  191.     just  have  to  specify  the  name  of  the function file. You may
  192.     specify as many input files as you want.
  193.  
  194.  
  195.  
  196. 3. Expressions:
  197. ----------------
  198.  
  199. This  section   describes   the   syntax  and  semantics  of  igensurf
  200. expressions.
  201.  
  202. A function file can contain comments. Comments are enclosed in { and }.
  203.  
  204. An expression contains real numbers, variable names,  function  calls,
  205. and the following operators:
  206.  
  207.                         + - * / ^
  208.  
  209. Operators  are  evaluated  left  to  right.  Powers  have  the highest
  210. precedence; multiplication and division are evaluated before  addition
  211. and  subtraction.  Expressions  can  be grouped with parentheses.
  212.  
  213. All values are double precision real.
  214.  
  215. In addition, variables and functions can be defined  by  the  user.  A
  216. variable definition has the form:
  217.  
  218.     var = expression;
  219.     
  220. Any  instance  of  the variable in an expression will be replaced with
  221. its definition. A function definition has the form:
  222.  
  223.     func(a1,a2,..) = expression;
  224.     
  225. The expression can contain instances of the function arguments as well
  226. as other variables and functions. Function  names  can  be  passed  as
  227. arguments.  Recursive  functions  can  be  defined  using calls to the
  228. defined function or other functions calling the defined function.
  229.  
  230. To define a constant expression, simply replace the equals sign  ('=')
  231. with a colon (':') in a definition. Constant expressions are evaluated
  232. only  once,  at  the  time  they  are  defined.  This  avoids repeated
  233. evaluation of expressions whose values never change. All values  in  a
  234. constant  expression must be previously defined, with the exception of
  235. function arguments. Constant function definitions are  useful  because
  236. they  will be replaced by their value in any expression that uses them
  237. with constant arguments. All predefined functions and  variables  have
  238. the  constants  attribute.  Thus "sin(PI/4)" in an expression would be
  239. immediately replaced by ".707108" unless sin() or PI were redefined by
  240. the user.
  241.  
  242. The  following  library  of  predefined  functions  and  variables  is
  243. provided:
  244.  
  245. step_s
  246.     The value of step_s supplied with the -s  option  on  the  command
  247.     line. You may change step_s if you want.
  248.     
  249. step_t
  250.     The value of step_t supplied with the -t  option  on  the  command
  251.     line. You may change step_t if you want.
  252.  
  253. PI
  254.     The ratio of a circle's circumference to its diameter.
  255.     
  256. if(cond,then,else)
  257.     if 'cond' is greater than zero,  'then'  is  evaluated,  otherwise
  258.     'else'  is  evaluated. This function is is necessary for recursive
  259.     definitions.
  260.     
  261. select(N,a1,a2,..)
  262.     return  aN  (N  is  rounded to the nearest integer). This function
  263.     provides array capabilities. If N is zero, the number of available
  264.     arguments is returned.
  265.     
  266. rand(x)
  267.     Compute a random number between 0 and 1 based on x.
  268.     
  269. floor(x)
  270.     Return largest integer not greater than  x.
  271.  
  272. ceil(x)
  273.     Return smallest integer not less than x.
  274.  
  275. sqrt(x)
  276.     Return square root of x.
  277.     
  278. exp(x)
  279.     Compute e to the power of x.
  280.  
  281. log(x)
  282.     Compute the logarithm of x to the base e.
  283.  
  284. log10(x)
  285.     Compute the logarithm of x to the base 10.
  286.     
  287. sin(x), cos(x), tan(x)
  288.     Trigonometric functions.
  289.     
  290. asin(x), acos(x), atan(x)
  291.     Inverse trigonometric functions.
  292.     
  293. atan2(y,x)
  294.     Inverse tangent of y/x (range -PI to PI).
  295.  
  296. hermite(P1, P2, P3, P4, t)
  297.     The 1-dimensional hermite polynomium.
  298.  
  299. bezier(P1, P2, P3, P4, t)
  300.     The 1-dimensional bezier function.
  301.  
  302. bspline(P1, P2, P3, P4, t)
  303.     The 1-dimensional b-spline function.
  304.  
  305. noise3(x, y, z)
  306.     The 3-dimensional noise function (-1 to 1).
  307.  
  308. noise3a(x, y, z)
  309.     The X slope of the noise function (-1 to 1).
  310.  
  311. noise3b(x, y, z)
  312.     The Y slope of the noise function (-1 to 1).
  313.  
  314. noise3c(x, y, z)
  315.     The Z slope of the noise function (-1 to 1).
  316.  
  317. fnoise3(x, y, z)
  318.     The fractal noise function (-1 to 1).
  319.  
  320. 4. Commands
  321. ------------
  322. It is possible to control igensurf by  using  commands  in  the  input
  323. files.
  324.  
  325. You can use commands to name objects, add surfaces to objects, start a
  326. new object,  control  surface  smoothing  and  to  activate/deactivate
  327. color, reflectance or transmittance computation.
  328.  
  329. A command has the form:
  330.  
  331.     #command arguments
  332.  
  333. Commands must start in column 1, and must be placed on a separate line.
  334.  
  335. The following commands are available:
  336.  
  337. #name [object_name]
  338.     Give new objects the name 'object_name'.
  339.  
  340. #add
  341.     Compute the surface, and add it to the current object.
  342.  
  343.     igensurf will execute an #add command before stopping, if  you
  344.         didn't issue an #add command anywhere in the input.
  345.  
  346. #write [object_name]
  347.     Write the current object to the TTDDD file  and  start  a  new
  348.         object.  If object_name is specified, the object will be given
  349.         this name. 
  350.         igensurf will execute a #write command before stopping, if the
  351.         current object hasn't been written to the output file.
  352.  
  353. #generate [object_name]
  354.     Compute the surface, and add it to the current  object.   Then
  355.         write it to the TTDDD file.
  356.     This is exactly the same as:
  357.         #add             followed by 
  358.         #write [object_name]
  359.  
  360. #scale scale_factor
  361.     Change the scale factor to 'scale_factor'.
  362.  
  363. #phong [on|off]
  364. #smooth [on|off]
  365.     Activate/Deactivate phong smoothing.
  366.  
  367. #color [on|off]
  368.     Activate/deactivate generation of face color info.
  369.     This  will  only  work  if  you  have  defined  the  functions
  370.         cr(s,t,x,y,z), cb(s,t,x,y,z) and cg(s,t,x,y,z).
  371.  
  372. #refl [on|off]
  373.     Activate/deactivate generation of face reflectance info.
  374.     This  will  only  work  if  you  have  defined  the  functions
  375.         cr(s,t,x,y,z), rb(s,t,x,y,z) and rg(s,t,x,y,z).
  376.  
  377. #trans [on|off]
  378.     Activate/deactivate generation of face transmittance info.
  379.     This  will  only  work  if  you  have  defined  the  functions
  380.         tr(s,t,x,y,z), tb(s,t,x,y,z) and tg(s,t,x,y,z).
  381.  
  382. 5. Examples:
  383. -------------
  384.  
  385. You can find some example files in "examples" directory.
  386.  
  387. Here is a list of the examples:
  388.  
  389. curtain.cal
  390.     Demonstrates how to use the noise functions to modify  a  surface.
  391.     The  resulting  object is something which should look a little bit
  392.     as a curtain:-)
  393.  
  394. hyper.cal
  395.     Functions used to create a hyperboloid.
  396.  
  397. mountain.cal
  398.     Demonstrates how to apply colors to a surface. 
  399.  
  400. sphere.cal
  401.     Functions used to create a sphere. This is much easier  done  from
  402.     within Imagine!
  403.  
  404. spiral1.cal
  405.     Creates some sort of spiral.
  406.  
  407. spiral2.cal
  408.     Creates another spiral.
  409.  
  410. super_el.cal
  411.     Creates a superellipsoid. Have a look at  this  example,  you  can
  412.     create a lot of different objects by varying a few parameters.
  413.  
  414. util.cal
  415.     This file contain some function definitions, which could be useful
  416.     when playing with igensurf.
  417.  
  418. teapot.cal + bpatch.cal
  419.     These files show how to use igensurf to create an object based  on
  420.     bezier  patch  data. This is the most complex example of them all.
  421.     It also show how to group surfaces together into 1 or more objects.
  422.     
  423. vase.cal
  424.     Creates a vase.
  425.  
  426. wastebasket.cal
  427.     Creates a wastebasket without bottom!
  428.  
  429. wave.cal
  430.     Create a wave.
  431.  
  432. All the examples should hopefully be self explanatory.
  433.  
  434. I've found, that just entering some equations and running the  program
  435. sometimes  lead  to  interesting objects; as the people at Impulse say
  436. all the time:
  437.  
  438.         Experiment, experiment, experiment... :-)
  439.  
  440.  
  441. 6. Credits:
  442. ------------
  443.  
  444. igensurf is written by Helge E. Rasmussen (her@compel.dk). It is based
  445. on code written by Greg Ward for the Radiance synthetic imaging system.
  446.  
  447. writetddd, which is needed if you want to use this program, is written
  448. by Glenn Lewis (glewis@pcocd2.intel.com), and is a shareware product.
  449.  
  450. You may use the program and the source code in any  way  you  want  as
  451. long  as  you  do  not resell the software as your own, or use it in a
  452. commercial product.
  453.  
  454. Please  let  me  know  if  you  find  any  bugs,  or  have  ideas  for
  455. enhancements.
  456.  
  457. Helge E. Rasmussen
  458.